Ensures that a text string fits into the specified pixel width, by truncating the string as necessary. This function makes use of the current script and font.

SInt16 TruncText (
    SInt16 width, 
    Ptr textPtr, 
    SInt16 *length, 
    TruncCode truncWhere
);

Parameter descriptions

width

The number of pixels in which the text string must be displayed in the current script and font.

textPtr

A pointer to the text string to be truncated. The text string can be up to 32 KB long.

length

On input, a pointer to a value containing the length, in bytes, of the text string to be truncated. On output, this value is updated to reflect the length of the (possibly) truncated text.

truncWhere

A constant that indicates where the text string should be truncated. You must set this parameter to one of the constants truncEnd or truncMiddle. If you supply the truncEnd value, characters are truncated off the end of the string. If you supply the truncMiddle value, characters are truncated from the middle of the string; this is useful when displaying pathnames.

DISCUSSION

You can use the TruncText function to ensure that a string defined by a pointer and a byte length fits into the specified pixel width, by truncating the string in a manner dependent on the font script.

TruncText uses the font script to determine how to perform truncation. If truncation occurs, TruncText inserts a truncation indicator which is the ellipsis (…) in the Roman script system. You can specify which token to use for indicating truncation as the tokenEllipsis token type in the untoken table of a tokens resource.

To determine the width of a string in the current font and script, use the QuickDraw StringWidth function.

SPECIAL CONSIDERATIONS

TruncText may move memory; your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)